Skip to content

feat(hippocampal): v2 memory system — glossary, namespaces, rollback, auto-inject, daemon#2933

Open
cy2311 wants to merge 6 commits into
Hmbown:mainfrom
cy2311:feat/auto-update-check
Open

feat(hippocampal): v2 memory system — glossary, namespaces, rollback, auto-inject, daemon#2933
cy2311 wants to merge 6 commits into
Hmbown:mainfrom
cy2311:feat/auto-update-check

Conversation

@cy2311

@cy2311 cy2311 commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Hippocampal Memory v2 — Glossary, Namespaces, Rollback, Auto-Inject, Background Daemon

This PR upgrades the hippocampal memory system from v1 (basic entity graph + FTS5) to a full-featured cross-session memory layer.

What's New

Storage Layer (crates/memory/)

  • Schema migration system with schema_version table for safe upgrades
  • namespaces table — workspace/project-level isolation
  • glossary table — keyword/tag system with many-to-many links to facts and entities
  • fact_versions table — full version history, enabling rollback to any previous version
  • 21 new store methods including namespace CRUD, glossary CRUD, fact versioning, rollback, and memory statistics

Agent Tools (crates/tui/src/tools/)

  • memorize — new glossary_tags[] and namespace parameters for structured tagging
  • recall — new namespace and glossary_tag filtering, glossary tag display in results
  • consolidatenew tool with four actions:
    • stats — memory usage report
    • rollback — restore a fact to a previous version
    • prune — delete low-importance facts (active forgetting)
    • merge — deduplicate identical facts

System Integration (crates/tui/src/core/engine.rs)

  • Auto-injects top-8 important facts into the system prompt as <memory_context> block on every refresh — the model sees cross-session knowledge without an explicit recall call
  • Background memory daemon via tokio::spawn: prunes low-importance facts (importance < 0.3, age > 30 days) every 6 hours, logs memory statistics
  • System prompt guidance telling the model to auto-call memorize when it discovers architecture decisions, user preferences, etc.

Design Document

See MEMORY_DESIGN.md for:

  • Architecture overview (3-layer: storage → tools → integration)
  • Why SQLite + FTS5 (not vector DB) — comparison table
  • Schema design rationale
  • Comparison with Mem0 (58k ⭐), Nocturne Memory, Awareness-Local
  • Future roadmap

Implementation Status

  • cargo check -p codewhale-memory
  • cargo check -p codewhale-tui
  • 9 unit tests in crates/memory/src/store.rs (4 original + 5 new)
  • Unit test execution blocked by disk space on dev machine

Changed Files

 M Cargo.lock
 M crates/memory/Cargo.toml                    (+tracing dep)
 M crates/memory/src/lib.rs                    (new exports)
 M crates/memory/src/schema.rs                 (migration system v1→v2)
 M crates/memory/src/store.rs                  (21 new methods, 5 tests)
 M crates/tui/src/core/engine.rs               (prompt injection + daemon)
 M crates/tui/src/core/engine/tool_setup.rs    (consolidate registration)
 M crates/tui/src/tools/memorize.rs            (+glossary_tags, +namespace)
 M crates/tui/src/tools/mod.rs                 (+pub mod consolidate)
 M crates/tui/src/tools/recall.rs              (+namespace/glossary filtering)
 M crates/tui/src/tools/registry.rs            (+with_consolidate_tool)
?? MEMORY_DESIGN.md                            (design document)
?? crates/tui/src/prompts/hippocampal_guidance.md
?? crates/tui/src/tools/consolidate.rs         (new tool)

Refs: #2933, Discussion #3234

@greptile-apps greptile-apps Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

@github-actions

github-actions Bot commented Jun 9, 2026

Copy link
Copy Markdown

Thanks @cy2311 for taking the time to contribute.

This repository is observing a maintainer-managed PR intake gate in dry-run mode, so this pull request is staying open. This note helps maintainers prepare the allowlist before any enforcement is considered.

Please read CONTRIBUTING.md for the expected contribution shape. A maintainer can grant recurring PR access by commenting /lgtm on a pull request.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the YOLO mode prompt markdown file by adding an instruction to execute actions directly without announcing or restating the current mode. It also changes the header level from H2 to H5. The reviewer recommends keeping the H2 header level to maintain consistency with other mode prompts.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

@@ -1,4 +1,4 @@
## Mode: YOLO
##### Mode: YOLO

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The header level was changed from ## (H2) to ##### (H5). To maintain consistency with other mode prompts (such as ## Mode: Agent and ## Mode: Plan) and to keep a clean hierarchy in the composed system prompt, it is recommended to keep this as an H2 header.

Suggested change
##### Mode: YOLO
## Mode: YOLO

@greptile-apps greptile-apps Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

@cy2311 cy2311 changed the title fix: suppress YOLO mode re-announcement before each action fix: tool unavailable error messages and YOLO mode verbosity Jun 9, 2026
@cy2311 cy2311 changed the title fix: tool unavailable error messages and YOLO mode verbosity fix: tool error messages, subagent name conflicts, and YOLO mode verbosity Jun 9, 2026

@greptile-apps greptile-apps Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

@cy2311 cy2311 force-pushed the feat/auto-update-check branch from c736324 to 63a0b3e Compare June 9, 2026 05:45

@greptile-apps greptile-apps Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

@cy2311 cy2311 changed the title fix: tool error messages, subagent name conflicts, and YOLO mode verbosity feat: hippocampal memory system, improved tool/subagent error messages, YOLO mode cleanup Jun 9, 2026
@Hmbown

Hmbown commented Jun 10, 2026

Copy link
Copy Markdown
Owner

@cy2311 — thank you, there's a lot of good work here. We'd like to take it, but in pieces, because it bundles two very different kinds of change:

The three fixes are wanted now. The YOLO-mode announcement suppression (#2922), the format_tool_error() clarity fix (#2657), and the subagent name-conflict elapsed-time message (#2656) are all small, reviewable, and address open milestone bugs. Please split them into one (or three) small PRs against current main and we'll merge promptly. Note #2951 just landed a related prompt note telling the model not to announce modes — your yolo.md line is complementary, just rebase over it.

The memory crate needs a design conversation first. A new crates/memory/ SQLite+FTS5 store with memorize/recall tools is an architectural decision that overlaps two existing tracks: the memory Phase 3 epic (#534) and the WhaleFlow external-memory design (docs/WHALEFLOW_EXTERNAL_MEMORY.md). Rather than merge a third memory architecture, let's reconcile on #2935 (your design issue): if accepted it would land opt-in/feature-flagged and coordinated with those tracks. Your entity/relation/fact schema with active forgetting is a genuinely interesting shape — we want the discussion, not to lose it.

Closing nothing here — this PR can stay open as the reference while the split PRs land.

Hmbown pushed a commit that referenced this pull request Jun 10, 2026
… subagent conflict messages (#3020)

Three targeted error-message improvements extracted from community
PR #2933 (author cy2311), with additional model-not-found annotation:

1. dispatch.rs format_tool_error: pass through self-explanatory messages
   that already name the cause (mode switch, allow_shell, feature flag,
   denied by user) instead of appending a conflicting generic suffix.
   Fixes the Plan-mode double-message (#2657).

2. subagent/mod.rs session-name conflict: include elapsed time
   (started Ns ago / NmNs ago) so the parent can distinguish a live
   worker from a stale/failed earlier spawn (#2656).

3. subagent/mod.rs annotate_child_model_error: catch model-not-found
   patterns (Model Not Exist, does not exist, no such model, etc.) in
   the raw error text even when the taxonomy classifies them as
   Internal rather than Authorization/State (#2653).

Closes #2653, #2656, #2657.
Credit: cy2311 for the dispatch.rs and subagent conflict hunks from #2933.

Co-authored-by: cy2311 <29836092+cy2311@users.noreply.github.com>
Hmbown added a commit that referenced this pull request Jun 11, 2026
… denial and provider errors

fix: harvest error-message fixes from PR #2933 — better tool denial + subagent conflict messages
@Hmbown Hmbown added the needs-human Agent blocked; requires human decision or credentials label Jun 11, 2026
@Hmbown Hmbown added this to the v0.9.0 milestone Jun 13, 2026
… auto-inject, daemon

Complete v2 overhaul of the hippocampal memory system:

Storage layer (crates/memory/):
- Schema migration system (schema_version table) for safe upgrades
- Namespaces table for workspace/project-level isolation
- Glossary table + fact_glossary/entity_glossary for keyword tagging
- fact_versions table for rollback support (every update saves history)
- New store methods: namespace CRUD, glossary CRUD, fact versioning,
  rollback, get_memory_stats, namespace-scoped queries
- 5 new unit tests (namespace, glossary, versioning, rollback, stats)

Agent tools (crates/tui/src/tools/):
- memorize: new glossary_tags[] and namespace input parameters
- recall: new namespace and glossary_tag filtering, glossary tag display
- consolidate: NEW tool — stats/rollback/prune/merge actions

System integration (crates/tui/src/core/engine.rs):
- memory_context_block(): injects top-8 important facts + usage guidance
  into the system prompt on every refresh (cross-session awareness)
- memory_daemon_loop(): background tokio task, prunes low-importance
  facts every 6 hours, logs memory statistics

Prompt guidance (crates/tui/src/prompts/):
- hippocampal_guidance.md: tells the model to auto-call memorize when
  it discovers architecture decisions, user preferences, etc.

Design doc: MEMORY_DESIGN.md covers architecture decisions, comparison
with Mem0 / Nocturne Memory / Awareness-Local, and future roadmap.

Refs: Hmbown#2933, Hmbown#3234
@cy2311 cy2311 requested a review from Hmbown as a code owner June 16, 2026 07:01

@greptile-apps greptile-apps Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

@cy2311 cy2311 changed the title feat: hippocampal memory system, improved tool/subagent error messages, YOLO mode cleanup feat(hippocampal): v2 memory system — glossary, namespaces, rollback, auto-inject, daemon Jun 16, 2026
@cy2311

cy2311 commented Jun 16, 2026

Copy link
Copy Markdown
Contributor Author

v2 Update — Design Research Complete

Hi @Hmbown, I took your advice from Discussion #3234 and did a deep research on how other projects implement memory systems before designing v2.

Research Sources

Project Stars Architecture
Mem0 58k ⭐ SQLite + Vector DB + LLM fact extraction
Nocturne Memory SQLite + FTS5, MCP server, OpenClaw drop-in replacement
Awareness-Local 213 ⭐ SQLite, MCP stdio/SSE, background daemon

Key Design Decisions (see MEMORY_DESIGN.md for full rationale)

  1. SQLite + FTS5 over Vector DB — keyword search is what coding agents actually need for structured fact retrieval. Vector search can be added later as an optional layer.
  2. Importance-scored facts (0.0–1.0) — unique among projects I studied. Enables active forgetting.
  3. Entity-relation graph — not just flat key-value. Enables graph walk queries.
  4. Auto-injection into system prompt — models see top-8 facts on every refresh.
  5. Schema migration system — inspired by Nocturne's approach, safe upgrades.

v2 Changelog

  • Glossary/tag system for cross-referencing facts and entities
  • Namespaces for workspace/project-level isolation
  • Fact versioning + rollback via consolidate rollback
  • New consolidate tool: stats / rollback / prune / merge
  • Auto prompt injection: <memory_context> block on every refresh
  • Background daemon: 6h interval prune + stats logging
  • Auto-memorize guidance in system prompt

Let me know what you think — happy to jump on WeChat to discuss further!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-human Agent blocked; requires human decision or credentials

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants